NetCloak 3.0 User's Guide: General Rules of NetCloak Syntax

	Version 3.0 User's Guide

General Rules Of NetCloak Syntax	Previous \| Next Contents

All NetCloak commands follow the same rules of syntax. Like HTML tags, every command must begin with an open angle-bracket ("<"), followed immediately by the command name. The command name is not case-sensitive, but for good form and recognizability, our examples and User's Guide show commands in all upper case.

Following the command name may be one or more parameters and a closing angle-bracket (">"). While the parameters may be optional, the closing bracket is required.

Specifying Repeating Parameters

Many SHOW and HIDE commands will accept multiple parameters in a series, and show or hide if any of them are matched. For example, the SHOW_DAY command accepts a day name as a parameter and so allows multiple days to be specified, as in:

    <SHOW_DAY BEGINS "SAT" "SUN">    This will show text on either Saturday or Sunday.

Specifying Optional Parameters

Commands which accept more than one type of parameter only allow one of each. The parameters are recognized by the order in which they appear, so ordering must always be closely followed. Some or all parameters may be optional, but to use the second or later parameters, all of the preceding parameters must be specified.

For example, the INSERT_DATE command allows an optional offset and an optional format parameter. The command may be used without any parameters, or with only an offset parameter: If multiple parameters are used, they must be included in order:

    <INSERT_DATE +24 SHORT>    <INSERT_DATE SHORT +24>

Of the two commands above, only the first will work correctly because the parameters are in the correct order.

Another example is the INSERT_COUNTDOWN command, which accepts the date you would like to count down to as the first parameter, and then the label for the weeks, days, hours, and minutes values. If you intended to use INSERT_COUNTDOWN with a different label for the days value, you might try using:

    <INSERT_COUNTDOWN_D 1/1/00 "x24 hours">

This would not work as intended. NetCloak will interpret "x24 hours" as the label for weeks, instead of days because the parameters are only interpreted in order. To use the second or later parameter in a command without specifying the preceding parameters, use a pair of quotation marks as a placeholder. The correct command for the previous INSERT_COUNTDOWN example would be:

    <INSERT_COUNTDOWN_D 1/1/00 "" "x24 hours">

The Commands section specifies the order of the parameters, whether the order is required and which parameters are optional for each command.

Parameter Wildcards

Many NetCloak commands allow you to specify an asterisk in place of a single character in a parameter, where the asterisk will match any character. This is commonly known as a wildcard.

For example, the following command will display the line following it to any "3.x" version of a browser:

    <HIDE><SHOW_CLIENT CONTAINS "3.*">    Please upgrade to version 4 of your browser.

INSERT commands do not allow wildcards. In most cases, a wildcard would not make sense for these commands. Wildcards are similarly disallowed in SHOW and HIDE commands which take numbers as a parameter, including COUNT, RANDOM and SAMERAND commands, or commands which take a date or a time as a parameter. The MACRO and EXEC_CGI commands do not allow wildcards in any of their parameters.

Variable commands (SHOW and HIDE LOCAL, GLOBAL or VARIABLE) will accept wildcards in parameters, however, you must use them carefully because an asterisk is also used as the multiplication operator. Enclosing parameters in quotation marks will generally prevent this type of problem, as well as making the commands easier to read. Wildcards do not work in variable values, however.

    <SET_VARIABLE myVar "bob">    <HIDE><SHOW_VARIABLE myVar IS "b*b">    This will be shown.

This example will show the text following if the value of the variable is "bob", "bib" or any other three letter combination starting and ending with "b". The opposite, where the wildcard is in the variable, will not work.

    <SET_VARIABLE myVar "b*b">    <HIDE><SHOW_VARIABLE myVar IS "bob">   This will not be shown!

The example above will not show the text even though the wildcard in "b*b" should match "bob".

TagBuilder

Included with NetCloak is a utility to make it easier to use NetCloak commands without having to memorize exact syntax or look them up the in the User's Guide. TagBuilder displays a floating window listing all of the NetCloak commands and allows you to drag and drop them into your documents, no matter what editor you are using. It also has a help window which will display syntax and a brief explanation of each command.

For BBEdit users, a version of TagBuilder is also provided as a BBEdit plug-in.

TagBuilder is not required to use NetCloak, but makes it much faster and easier to get started and provides a handy reference any time.

Whitespace Characters

Parameters within NetCloak commands are separated by one or more spaces, tab characters or line breaks (collectively known as the "whitespace" characters). For example, the following command contains four parameters after the command name -- "Country", "CONTAINS", "USA", and "Canada":

    <HIDE_GLOBAL Country CONTAINS USA Canada>

If you omit a space between parameters, the meaning of the command changes, and you will get unexpected results. For example, the following command only contains three parameters ("Country", "CONTAINS", and "USACanada"), and thus behaves differently:

    <HIDE_GLOBAL Country CONTAINS USACanada>

You may use any combination of whitespace characters between command parameters to improve readability of the HTML source code. For example, the following two commands are treated exactly the same by NetCloak:

    <SET_VARIABLE Total = Item1Total + Item2Total + Item3Total + Item4Total 
    + Item5Total + Shipping + Tax>    
    <SET_VARIABLE
       Total = 
            Item1Total +
            Item2Total +
            Item3Total +
            Item4Total +
            Item5Total +
            Shipping +
            Tax
    >

Quotation Marks

In most cases, parameters can be placed in quotes , but quotes are not required. For example:

    <SHOW_CLIENT CONTAINS "mozilla">

is functionally equivalent to:

    <SHOW_CLIENT CONTAINS mozilla>

Using quotes, however, allows you to include spaces within a parameter. For example:

    <SHOW_CLIENT CONTAINS "mozilla 3.0">

is very different from:

    <SHOW_CLIENT CONTAINS mozilla 3.0>

The first case looks for a client that contains "mozilla 3.0", but the second will recognize either client names that contain "mozilla" or client names that contain "3.0". This is because the space between "mozilla" and "3.0" is interpreted by NetCloak as a delimiter between parameters instead of the space that appears in the browser name.

When a parameter is set inside quotes, you must use two double-quote characters to specify a quote, so that NetCloak does not interpret the quote character as the end of the parameter. For example:

    <HIDE_VARIABLE SomeVar "He said ""moof""!">

This command would look for the string He said "moof"!, because NetCloak interprets the two double-quote marks as a quote instead of the end of the parameter.

Quotes may not be used around variable names. If a variable name is enclosed in quotes it will be interpreted as a text string and not a variable name. For example, if you have a local variable called "TestVar" that is set to the value "Moof", you might do something like this:

    <SET_LOCAL NewVar = "TestVar" & " Says the Dogcow">    <INSERT_LOCAL NewVar>

This would display:

    TestVar Says the Dogcow

What is really desired is this:

    <SET_LOCAL NewVar = TestVar & " Says the Dogcow">    <INSERT_LOCAL NewVar>

Resulting in:

    Moof Says the Dogcow

In the first example TestVar is specified as a string and NetCloak inserts it accordingly. In the second, NetCloak recognizes that TestVar may be some other kind of entity, and evaluates it correctly.